<HTML>

<BODY BGCOLOR="white">

<center>
<FONT SIZE=+2 COLOR="#BB0000">CS346 - Spring 2011<BR>Database System Implementation</FONT>
</center>

<p>
<table border=0 cellpadding=4 cellspacing=10 width="100%">
<tr><td width="100%" bgcolor="#ccccff"><font face="Arial">
<center><b>A General Statistics Tracker for RedBase</b></center>
</font></td></tr>
</table>

You may find it useful to track certain statistics as your RedBase
system executes.  For example, you may want to know what percentage of
page requests were found in the buffer pool, or how many times a
particular file was flushed to disk.  Later on you may want to track
statistics about index behavior or query processing.  We are providing
a general statistics package for your use, encapsulated in the
<tt>StatisticsMgr</tt> class described below.

<P>Statistics are collected and reported only if flag
<tt>-DPF_STATS</tt> is included during compilation.  We have already
set up statistics reporting within the buffer manager of the PF
component.  We track the total number of read-page and write-page
requests that the buffer manager issues to the file system.  In
addition to buffer I/O statistics, we track the total number of page
requests sent to the buffer manager, along with the number of pages
found in the buffer versus those that needed to be be fetched from
disk.  A complete list of the PF statistics <i>keys</i> (more on this
below) can be found in the file <tt>pf_statistics.h</tt>.

<h3> StatisticsMgr Class </h3>

The <tt>StatisticsMgr</tt> class enables dynamic tracking of
statistics.  Each statistic to be tracked is identified by a
<i>key</i>, which is a distinct character string such as
"<tt>WRITEPAGE</tt>".  Every key that has been registered with the
statistics manager has an integer value associated with it,
representing the current value of that statistic (such as the number
of pages written to disk so far).

<p>If you want to use the statistics package, your program should
create one instance of the <tt>StatisticsMgr</tt> class, with all
requests to track statistics being directed to that one instance.
Below, the public methods of the class declaration are shown first,
followed by descriptions of the methods.  As usual, the first two
methods in the class declaration are the constructor and destructor
methods and are not explained further.  Nonzero return codes are
discussed within the method descriptions.

<p>For an example of how we used the statistics package in our tests of
the PF component, see <tt>pf_test2.cc</tt>.

<pre>
class StatisticsMgr { 
  public: 
    StatisticsMgr  ();                       // Constructor 
    ~StatisticsMgr ();                       // Destructor

    // Register a new statistic or track a change to an existing one
    RC Register    (const char * const psKey, 
                    const Stat_Operation op,
                    const int * const piValue = NULL);   

    // Get value for a statistic.  Caller must delete returned object.
    int* Get       (const char *psKey);      

    RC Print       (const char *psKey);      // Print value for a statistic
    void Print     ();                       // Print all statistics values
    RC Reset       (const char *psKey);      // Reset value of a statistic
    void Reset     ();                       // Reset all of the statistics
 };
</pre>

<h4>
RC Register (const char * const psKey, const Stat_Operation op,
             const int * const piValue = NULL)   
</h4>

This is the controlling method for the statistics package.  This
method is called to track changes to an existing statistic, or to
create a new statistic to track.  <tt>psKey</tt> is an identifier (or
key) for one statistic.  <tt>op</tt> is a <tt>Stat_Operation</tt>
indicating what operation to perform on the statistic.  Valid values
for <tt>Stat_Operation</tt> are:

<ul>

<li> <tt>STAT_ADDONE</tt>, which increments the current value for the
statistic (and does not require a <tt>piValue</tt>)

<li><tt>STAT_ADDVALUE</tt>, which adds the value pointed to by
<tt>piValue</tt> to the current value of the statistic

<li><tt>STAT_SUBVALUE</tt>, which subtracts the value pointed to by
<tt>piValue</tt> from the current value of the statistic

<li><tt>STAT_MULTVALUE</tt>, which multiplies the current value of the
statistic by the value pointed to by <tt>piValue</tt>

<li><tt>STAT_DIVVALUE</tt>, which divides the current value of the
statistic by the value pointed to by <tt>piValue</tt>

<li><tt>STAT_SETVALUE</tt>, which sets the value of the statistic to the
value pointed to by <tt>piValue</tt>

</ul>

If <tt>psKey</tt> is an identifier not yet associated with a statistic,
then a new statistic is added to the statistics manager with an
initial value of 0.  The operation <tt>op</tt> is then performed as
indicated above.

A return code of 0 indicates success, while the positive return code
<tt>STAT_INVALID_ARGS</tt> indicates invalid arguments in the method
call.

<h4>
int* Get (const char *psKey)     
</h4>

This method returns a pointer to a copy of the current value of the
statistic named <tt>psKey</tt>.  If no statistic with that name exists
then <tt>NULL</tt> is returned.  The caller is responsible for deleting the
memory returned by this method.

<h4>
RC   Print (const char *psKey)<br>
void Print ()
</h4>

These are simple methods that write the name of a statistic followed
by its current value to the Unix <tt>stderr</tt> output stream.  If
<tt>psKey</tt> is included then only that statistic is printed;
otherwise all statistics are printed.  When <tt>psKey</tt> is included
the possible return codes are: 0 for success,
<tt>STAT_INVALID_ARGS</tt> when psKey is <tt>NULL</tt>, or
<tt>STAT_UNKNOWN_KEY</tt> when psKey is not a statistic known to the
system.

<h4>
RC   Reset (const char *psKey)<br>
void Reset ()
</h4>

These methods reset the values of one or all statistics to 0.  When
<tt>psKey</tt> is included (to reset only one statistic) the possible
return codes are: 0 for success, <tt>STAT_INVALID_ARGS</tt> when psKey
is <tt>NULL</tt>, or <tt>STAT_UNKNOWN_KEY</tt> when psKey is not a statistic
known to the system.


</BODY>
